\documentstyle[a4,12pt,desc,verbfile,blockpar]{article}
\begin{document}

% Tm version number
\def\version{\input{version}}
% Some logos
\def\tm{\bf tm}
\def\C{\bf C}
\def\cvr{\bf cvr}

% Width of description column in tabular environments.
\newlength{\descwidth}
\setlength{\descwidth}{0.7\textwidth}
\setcounter{tocdepth}{2}

\title{{\cvr} library Manual \\ {\Large version {\version}}}
\author{C. van Reeuwijk \\ Delft University of Technology}
\maketitle
\section{Introduction}
This manual provides the necessary information to use the {\cvr}
library, a collection of utility functions.
The functions are described using an ANSI {\C} style type specification.
This does not imply that an ANSI {\C} compiler is required.
\section{Symbol handling}
These functions maintain a table of strings.
Each time a string is added to the table,
a value of type {\tt symbol} is returned.
It is guaranteed that for equal strings the same value is returned,
and it is possible to compare these values with a simple compare ({\tt ==}).
There is a special `nil' value, {\tt symbolNIL}.
\par
Before the symbol routines may be used, they must be initalized with\linebreak
{\tt initsymbol()}.
\begin{verbatim}
symbol addsymbol( char *name );
\end{verbatim}
\begin{desc}
Add string {\tt name} to the symbol table.
If the string already occurs in the table, the value of the old
entry is returned, else a new entry is added, and a new value is returned.
\par
This routine ensures that for all symbols with the same name,
the same value is returned.
\end{desc}
\begin{verbatim}
symbol findsymbol( char *name );
\end{verbatim}
\begin{desc}
Try to locate string {\tt name} in the symbol table.
If it occurs in the table, its value is returned,
else {\tt symbolNIL} is returned.
\end{desc}
\begin{verbatim}
void flushsymbol();
\end{verbatim}
\begin{desc}
Empty the symbol table, and free all memory allocated to it.
It is allowed to start using {\tt addsymbol()} or {\tt gensymbol()} again.
\end{desc}
\begin{verbatim}
symbol gensymbol( char *prefix );
\end{verbatim}
\begin{desc}
Given a string {\tt prefix}, generate a new symbol value with a new string.
It is not allowed to use {\tt addsymbol()} after you have used
{\tt gensymbol()}.
Otherwise it cannot be guaranteed that the generated symbols remain unique.
This restriction is enforced by the routines.
\end{desc}
\begin{verbatim}
void initsymbol();
\end{verbatim}
\begin{desc}
Before the other symbol routines are used,
this function must be called to initalize the internal variables.
\end{desc}
\begin{verbatim}
char *symbolstr( symbol s );
\end{verbatim}
\begin{desc}
Given a symbol {\tt s},
return a pointer to the string of that symbol.
\end{desc}
\begin{verbatim}
void setprior( symbol s, int n );
int getprior( symbol s );
\end{verbatim}
\begin{desc}
Each symbol has an associated {\em priority}.
This indicates in general how `important' the symbol is.
For new symbols created by {\tt addsymbol()} it is set to 2,
for new symbols created by {\tt gensymbol()} it is set to 0.
It may be accessed by the function {\tt getprior()},
may be changed by the function {\tt setprior()}.
\end{desc}
\begin{verbatim}
void fre_symbol( symbol s );
void rfre_symbol( symbol s );
symbol rdup( symbol s );
int fscan_symbol( FILE *f, symbol *s );
void print_symbol( symbol s );
void fprint_symbol( FILE *f, symbol s );
int cmp_symbol( symbol a, symbol b );
\end{verbatim}
\begin{desc}
Tm C functions for type {\tt symbol}.
\end{desc}
\section{Checked UNIX functions}
These functions provide a small layer on top of standard UNIX functions
to check for error conditions, and to print an error message if necessary.
Some functions also do an {\tt exit(1)}.
All these functions are prefixed with `{\tt ck}'.
Thus, {\tt ckmalloc} is a checked version of {\tt malloc}.
\par
\begin{tabular}{ll}
\multicolumn{1}{c}{Function} & \multicolumn{1}{c}{{\tt exit(1)}} \\
\hline
{\tt ckcalloc} & yes \\
{\tt ckmalloc} & yes \\
{\tt ckrealloc} & yes \\
\end{tabular}
\section{Debug flags}
These functions can be used to maintain a list of debugging flags.
They use a table of debugging flags with the following structure:
\begin{verbatim}
typedef struct _cvr_db_flags {
    char flagchar;       /* char to switch the flag on */
    int *flagadr;        /* pointer to the flag */
    char *flagdescr;     /* description */
} dbflag;

#define dbflagNIL (dbflag *)0
\end{verbatim}
The table can be constructed as an initialized array of type {\tt dbflag}.
The last entry in the table should have {\tt flagchar} \verb!'\0'!.
For example:
\begin{verbatim}
dbflag flagtab[] =
{
    'a', &flaga, "flag a",
    'b', &flagb, "flag b",
    '\0', 0, ""
};
\end{verbatim}
\par
Each debugging flag is identified with a character {\tt flagchar},
and has an associated variable {\tt flagadr}.
There is also an associated description string {\tt flagdescr}
that is printed by the function {\tt helpdbflags()}.
\par
There is no routine to initialize the flag variables.
\par
\begin{verbatim}
dbflag *finddbflag( char c, dbflag *table );
\end{verbatim}
\begin{desc}
Given a character {\tt c}, and a table of debugging flags {\tt table},
return a pointer to the entry of the debugging flag {\tt c}.
Return {\tt dbflagNIL} if {\tt c} does not occur in the table.
\end{desc}
\begin{verbatim}
void helpdbflags( FILE *f, dbflag *table );
\end{verbatim}
\begin{desc}
Given a file handle {\tt f}, and a table of debugging flags {\tt table},
write an overview of the available flags in {\tt table} to file with handle
{\tt f}.
\end{desc}
\begin{verbatim}
void setdbflags( char *s, dbflag *table, int val );
\end{verbatim}
\begin{desc}
Given a string of debugging flags {\tt s},
a table of debugging flags {\tt table},
and a value {\tt val},
search {\tt table} for each of the flags in {\tt s}, and assign to the
associated flag variable the value {\tt val}.
All other flag variables are left unchanged.
\end{desc}
\end{document}
